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Here is a ragtag assortment of odds and ends from Apple III. thrown 

?r s, h umaimed * l0gical have al^dy Z 

pu bhshed elsewhere; some are obtainable in the fine print of Apple man- 

S hX 3 ' 6 *T frUi ' ° f PerS ° na ' '"^igaUon'Accura^S. 

&?h£T*T*? y ' m r y " 0t ■* Uniformly n « h ' So * earned. 
easi« thin^n ,h ^"f ,nfom,ation from Apple Computer isn't the 

the APpt »I ?,^f Th 4 " ^L" S USUa " y faStW ' and more fun ' 10 
r2L . * here 13 no obv,ous reason f or Apple's reticence The 

folk, at Apple intend, they say. to publish the SOS Refere^e Mall 

aTread e v Ven mo al,y • '!* **" ^ The 
£ If" vou V°L ^ 35 3 teXtb0 ° k f0f the "' Techni ^ W ork- 
™L S * " °" Wn " ng assembl y <°r *e by all 

eTemhl " ^ u" •* y0U ,0tS and ,ots ' """""S" quite 

Z 1 a . ^ Programmers, which you might suppose would not 
£ niou^ of S ™ P"^»n,eS°i„g e Jf^ 

No doubt a recognized software development firm, prepared to sign 



attain agreements can obtain source materials and technical assistance 
But many bright ideas must incubate and grow and be played with on 
the machine before they become sufficiently clear and explicit to warrant 

v/STh k " ? APPle ' A k " ° f ma y*- w "°ulds "lust simply have 
vanished because the programmer had insufficient information to per- 
mit experimentation. ^ 

A Memory Map. At any one time, the 6502 cpu works with 64K ad- 
dresses arranged as follows: 



0000.. 1FFF 
lower s-bank 



2000. 9FFF 
user bank 0-6 



A000..FFFF 
uppers-bank 

The system bank is always on-line. It contains SOS.Kernel and other 
goodies. The user banks are switched in and out. Only one user bank is 
on-line at any given moment. 

Table 1 describes the function of pages in the lower system bank 

SB^n P Tpp| y V em . ^ SA000 "FFFF. SOS.Kernel occupies 
SBC00..FFFF. In the future SOS.Kernel may get longer and extend 
down as far as SB8O0. SOS.Interp. which is "absoLe" cL, SnoSSj 
loaded below SOS.Kernel. Actually, it is loaded into the higheT^ 

cat.cn ($7600 for Pascal). It may then extend upward for any Icntth un 
to the low* oid of SOS.Kernel (presently JBCOO). Thus ifZSSfoWr' 
laps from bank 6, a user bank, into system bank $A000..BBFF This is 
important because the overlap gives the interpreter a sizable area in sys- 
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6b: 



01 



02.. 03: 
04.. 07: 

08. .0B: 



.13 



0C..0F 
10.. 11 
12. 
14: 

15: 
16: 

17: 
18: 
19: 
1A: 
1B: 



1C..1D: 
1E..1F: 



"True" zero page. Used early in boot sequence, and as the 
zero page for interrupt handlers. 

"Normal" 6502 stack. Addressed by PHA, JSR, and so on 
whenever bit 2 of environment register ($FFDF) is set. Used as 
stack page by interrupt handlers, drivers, and by SOS Kernel 
itself. 

I/O buffers for floppy drivers. 

Text page 1. In eighty-column mode holds screen memory for 
even-numbered columns 0,2,. .78 (decimal). 
Text page 2. Memory for odd-numbered columns 1,3,. 79 
(decimal). Note: Corresponding addresses in TextPagel and 
TextPage2 are interchanged by the relation: (high byte) XOR 

$oc. 

Character set. 

File names, prefix, ? access routes to files. 

Used as I/O buffer for reading directories. 

Xbyte page when zero page is $18. Used by SOS. Kernel and 

by drivers. 

Typeahead buffer. 

Xbyte page when zero page is $1A. Used by interpreter and by 
assembly modules included in user programs. 
Keyboard layout. 

System zero page. Used by SOS. Kernel and by drivers. 

SOS data and jump tables. 

"User" zero page. Used by interpreter. 

"Alternate" 6502 stack when zero page is $1A (zero page XOR 

$01). Used by interpreter. Alternate stack is addressed by 

PHA, JSR, and so on, whenever bit 2 of environment 

register ($FFDF) is clear. 

Route information for open files. 

Available for use by interpreter. 

Table 1. Lower system bank: pages $00 . 1F. 



tern bank for code that is always on-line. Bank-switching must always be 
done from system bank. If you switch banks while running in a user 
bank— -puuffl Suddenly you aren't. 

A very short interpreter might lie only in user bank or only in system 
bank. The loading site and length are determined by the writer when the 
interpreter is created. It is absolute code ".org'd" on the intended load- 
ing site. 

Usually the upper system bank is all RAM, except for 
$FFD0..FFDF and $FFE0..FFEF, which are the onboard D and E 
VI As (versatile interface adapters). In particular, if bit 6 of the environ- 
ment register is clear, then SC000..CFFF is RAM. If that bit is set, then 
this area is I/O. There are also $20 bytes of RAM "under" the VIAs at 
SFFD0..FFEF. Normally they are ofT-line. These RAM bytes can be ac- 
cessed only by "8F" extended addressing. This small area of RAM is 
unique in that it is not disturbed by a control-reset reboot, so that's 
where they keep the last valid clock value— less useful, since you ob- 
tained your functioning clock chip. 

The RAM of SOS.Kernel area $C000..FFFF can be write-protected 
by setting bit 3 of the environment register. Normally this RAM is pro- 
tected while the interpreter is running. This is the user environment, and 
Apple doesn't trust you. It is unprotected in the driver, SOS.Kernel, 
and interrupt handler environments. Write-protection doesn't affect 
I/O SCO0O..CFFF when that is enabled, nor the VIA registers 
$FFD0..FFEF. 

Highest User Bank: Bank 6 in a 256K Machine. At boot time 
SOS.Interp is loaded here, at whatever site the writer has designated, as- 
suming, as is usually the case, that the interpreter is not confined entirely 
to SA000..BBFF in system bank. Next the drivers are loaded below 
SOS.Interp, one after another, in whatever order they are encountered in 
SOS. Driver, which is just the reverse of the order listed by the System 
Configuration Program. For this purpose n modular driver inct on. 
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ivcr, no matter how many modular units it may contain. The drivers 
tend, pessary, down to the bottom of bank 6. If more space is 
eded] continue from the top of the next lower user bank (S9FFF 
th bank 5 switched in). Each driver, however, must be completely con- 
aicd within its bank, so if there is insufficient room for the complete 
iver in bank 6 it will be placed entirely in bank 5. Any space left over 
Oow the drivers is free and available for requisition by the interpreter. 

Interpreter Strategy. Interpreters should never assume they are resi- 
st in the highest bank, even though that is where they* are normally 
aded. Interpreters will run perfectly well in other banks. All you need 
»do is copy the user bank portion of the interpreter into the correspond- 
,g bytes in another (free and available) bank. Then switch in that bank 
cing careful not to self-destruct) and perform a jump to the first byte of 
fccrpreter code. The interpreter still overlaps into system bank 
iA000..BBFF) just the way it always did. Bank-switching affects only 
« user bank. Interpreters, therefore, should always find out where they 
it by checking the bank register ($FFEF), never by making assump- 
ons or by using location $1901, which does contain the highest bank 
umber. 

This relocation trick can be used for interpreter-switching schemes. A 
mall switching interpreter is loaded from disk as the original 
iOS.Interp. It is placed entirely in the upper part of the highest user bank, 
vith the drivers immediately below. The switching interpreter, in turn, 
□ads in another interpreter (perhaps Pascal) but places the user-bank 
^rtion in a lower bank, wherelt runs very happily. The switching inter- 
preter remains in the highest bank, taking up very little room, just wait- 
ng for you to call it back by pressing a special key combination (for 
*hich you will need a small modification of the console driver). Then the 
Pitching interpreter can load in, and run, some other interpreter, such as 
Itisic. 

Bank 0: 44 8F" Addressing. The "zero-page anomaly" m Apple 
HI m that every time the 6502 executes a zero-page instruction it ac- 
naally operates on the designated zero page, found as the value of the 
j-ero-page register (SFFD0). The same thing happens when the (sixteen- 
th) operand of an instruction has $00 in the high byte, since that also re- 
fers to zero page. Similarly, in extended addressing, if the place you are 
•fceaded has $00 in the high byte of its address, then that is also interpret- 
ed as a zero-page location and you are given whatever is the current zero 
-age. But that may not be what you want. 

Extended addressing looks at a 64K stretch of memory comprising 
h*o consecutive user banks. In extended addressing, $0000 is the bottom 
done user bank and $FFFF is the top of the next higher user bank. 
Whichever pair of user banks is active depends on the Xbyte of the ex- 
tended address. This works fine except for the lowest page of the lower of 
;tfee two user banks in the pair. That would have to be addressed as 
S9Q*jc/8b. But the high byte of that address is $00, so you are given zero 
,fiage instead. 

Normally you get around the zero-page anomaly by decrementing 
he Xbyte. Then you are looking at a different pair of user banks, with 
our target bank as the higher member of the pair. The lowest page of 
hat bank can then be addressed as $80xx/8b-l. But what about the 
lowest page of bank 0? There is no lower user bank to put underneath it 
m a pair. Hence 8F addressing. 

8F is an Xbyte which, when present, causes the extended addressing 
mechanism to look at 64K of memory constructed as follows: 



0000.. 1FFF 
lower s-bank 



2000..9FFF 
bankO 



A000..FFFF 
upper s-bank 



It is almost exactly like system addressing (Xbyte $00), with bank 
swit 1 in. (There is one other interesting feature. It is all RAM, in- 
due,. . e the RAM beneath the VIA registers $FFD0..FFEF.) 

Thus if you are doing a lot of talking to user bank 0, you should use 
8F as the Xbyte and address the bank as $2000..9FFF, corresponding to 
50000..7FFF in the bank. Then you can get to the lowest page without 
worrying about the zero-page anomaly. 

User Bank 0: Graphics. Which, of course, is why you'll want to be 
Balking to bank 0. That's where graphics arc, when graphics are allo- 
cated. Pascal and Basic each provide for allocations of $00, $40, or $80 



pages of graphics, depending on the graphics mode. Pascal also allows 
$20 pages, which is enough for one lo-res black-and-white buffer. Hi-res 
mode appears to interleave two lo-res modes in alternate columns or 
groups of pixels, much as eighty-column text interleaves two forty-col- 
umn screens. . 

The number of pages allocated for graphics is stored in location 
$1907 in the SOS data area. Presumably this byte is used by the video 
generator apparatus, as are surrounding bytes in that area. 

In black-and-white lo-res mode (BW280), buffer 1 runs from 
$2000/208F..3FFF/3F8F (which is $0000.. 1FFF in bank 0). Buffer 2 is 
found in S4000/408F..5FFF/5F8F. In buffer I the lowest byte ($2000/ 
2081) represents the upper-lefl corner of the screen. Each bit repre- 
sents one pixel. Successive bytes (and their contained bits) are in order 
from the left edge of the screen. One accesses individual bytes by indirect 
Y-indexed addressing (extended addressing) off the base address, which 
is the leftmost byte in that horizontal row. The following algorithm (for 
BW280, buffer 1) relates corresponding bytes in successive rows. It was 
discovered empirically and is doubtless pathetically slow. 

next line up: subtract $0400 

it < $2000 then add $2000 and subtract $80 
if < $3C00 then add $0400 and subtract $28 

next line down: add $0400 

if > = $4000 then subtract $2000 and add $80 
if > = $2400 then subtract $0400 and add $28 

In hi-res mode (BW560) alternate bytes (groups of eight pixels) come 
from corresponding bytes of the two lo-res buffers just discussed. Thus 
the sequence is $2000, $4000, $2001 , $4001 .... Hi-res buffer 2 is the cor- 
responding structure beginning at $6000/608F. In color mode (CP280) 
the "upper lo-res buffer" presumably contains color information. We are 
not sure about COL140 mode. And we are not sure if the base address 
algorithm holds for these modes. 

When you are ready for the video generator to display your graph- 
ics, it is necessary to fiddle with the soft switches (sec table 8). Graphics 
information is always taken from bank 0, regardless of which user bank 
is switched in. Presumably this is hard-wired, although it is just conceiv- 
able that the source bank is software-selected. If so, we don't know how. 

The Text Pages: S0400..07FF and $0800..0BFF. Apple III text 
memory is very similar to Apple II; possibly identical for forty-column 
mode. In eighty-column mode the two "text^ages" are interleaved: even 
columns from $0400..07FF, odd columns from $0800..0BFF. The rea- 
son for this peculiar arrangement is found in the direct memory access 
(DMA) apparatus of the video generator. When Apple III was designed 
for an eighty -column display, the video generator had to call up twice the 
amount of information as it did for the forty-column display of Apple II. 
But it did not have twice the time in which to do it. So the memory-fetch 
path in Apple III was made sixteen bits wide. Every data fetch actually 
gets two bytes. The video generator uses both. The 6502 chip uses one 
and ignores the other (except in the case of the Xbyte, which is that extra 
byte used in extended addressing). The memory fetch does not get two 
adjacent bytes. It gets the byte at address and the byte at address: high 
byte XOR $0C. Thus a fetch to $0400 also gets the byte from $0800, 
which the video generator puts in the odd column. And this is also the 
reason why the Xbyte page is related to its zero page by the same rela- 
tion, high byte XOR $0C. 

The Apple II "screen holes" are there, but you aren't supposed to use 
them for peripheral card scratchpad space. In the Apple III these loca- 
tions are used as transfer ports when downloading character sets to the 
video generator. But downloading occurs only at boot time or when pro- 
grams deliberately change character sets. It is relatively rare. The rest of 
the time these locations seem to be idle. It may be that a peripheral card 
could use them for a while. But it's illegal according to the definition of 
Apple III. 

It is possible to write directly to the screen from assembly, bypassing 
the console driver. Just put ASCII codes in the appropriate memory lo- 
cations. The high bit should be clear for inverse and set for normal, as- 
suming you are using a standard (not inverted) character set. 

The bytes in each horizontal line are accessed by X-indexed address- 
ing ofT the base address, which is the leftmost byte of that fine (sec table 2). 
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odd, add $0400 to the address. 

:- column DIV 2; 



If column is 
Use X index 

00 0400 

01 0480 

02 0500 

03 0580 

04 0600 

05 0680 

06 0700 

07 0780 

Table 2. Text screen line numbers versus base addresses. 



08 
09 
OA 
0B 
0C 
0D 
0E 
OF 



0428 
04A8 
0528 
05A8 
0628 
06A8 
0728 
07A8 



0450 
04D0 
0550 
05D0 
0650 
06D0 
0750 
07D0 



In eighty-column mode use X column DIV 2. If the column number 
is odd, you must also add $0400 to the base address given in the table. 
Alternatively, the base address and index may be computed with a mod- 
ification of the Apple II subroutine Bascalc (table 3). 



bascalc 



$1 



Entry: 


Line, column 








Exit : 


Base address (addrL.H), 


X-index 






Ida 


line 




asl 


A 


pha 






ora 


addrL 


Isr 


A 




sta 


addrL 


and 


#03 


which 


Ida 


column 


ora 


#04 




Isr 


A 


sta 


addrH 




tax 




pla 






bcc 


$2 


and 


#18 




Ida 


addrH 


bcc 


$1 




eor 


#0C 


adc 


#7F 




sta 


addrH 


sta 


addrL 


$2 


rts 




asl 


A 










Table 3. Subroutine Bascalc. 







The Character Set: S0C0O..0FFF. At boot time the system charac- 
ter set is loaded from SOS.Driver and stored in these pages. Similarly, if 
you download another character set from a program by issuing a 
DControl call §\ 6 or #17 to the console driver, the new set is also placed 
here. But these pages are not the active character set in current use by the 
video generator. This is merely a staging area. From these four pages the 
character set is further transferred to the video generator's storage area, 
wherever that is. It is not in addressable memory. Presumably the ma- 
chine contains a IK RAM chip dedicated for this purpose, analogous to 
the ROM chip beneath the Apple II keyboard that contains the charac- 
ter set for that machine. In any event, you can change the copy in 
$0C0O..OFFF all you wish, but nothing happens. 

The console driver uses a complex mechanism to transfer the charac- 
ter set into the video generator. It sets up an internipt-driven back- 
ground program (spooler) by allocating system internal resources (SIR) 
numbers $05, $06, and $10. The video-generator mechanism then inter- 
acts with the SIR#06 interrupt handler (embedded in the console driver) 
to transfer the character definitions at its leisure. The computer's atten- 
tion is returned to the user's programs, and the video generator inter- 
rupts when it feels ready for another swallow. There may be simpler ways 
if you are willing to let the main program wait. For an entire character 
set the download procedure takes about a second to complete. 

The actual transfer involves trie E-VIA's peripheral control register 
($FFEC), interrupt enable register ($FFEE), a couple of sites in SCOOO 
I/O space ($C0DA and SC0DB) that are probably soft switches, and the 
notorious screen holes. Apparently the interrupt handler moves the char- 
acter descriptions piecemeal from the $0C00 area to the screen holes and 
then alerts the video generator to move them on from there into its own 
dedicated RAM. 

This transfer could probably proceed just as easily from any mem- 
ory buffer to the screen holes; the $0C00 staging area is merely a conven- 
ience. But if you are operating from a background program, and if that 
program is the interrupt handler itself, then the buffer must be in system 
bank. If the buffer were in a user bank it would surely go off-line due to 
bank-switching. Extended addressing is not available for interrupt han- 
dlers; it doesn't work on the true zero page. Hence the $0C00 buffer. 

Typehead Buffer: S1500..15FF. Page $15 is set aside for use by the 
console driver as a typeahcad buffer. It is nothing more than a first-in- 
ftrst-out queue. Actually two queues. The first queue ($1500..157F) con- 
tains KBD values, which are the ASCII codes generated by the key- 
board. For each KBD there is also a KBDFLG byte, the second key- 
board byte, which flags the various modifier keys. KBDFLG is stored in 



the corresponding byte in the second queue ($1580..15FF). The console 
driver maintains a count of the current number of characters in the 
queue and keeps index pointers to the current front and rear of the 
queue. 

When a key is pressed, KBD appears at $C000 just as it does in Ap 
pie II. At this time KBDFLG also becomes available at $C008. The ke> 
board interrupt is cleared with the keyboard strobe, SCO 10, just as it is in 
Apple II. 

KBD and KBDFLG are picked up by the keyboard (SIR#02) inter- 
rupt handler, which is embedded in the console driver. If they Represent 
one of the five console control keys, that function is executed immedi- 
ately. Otherwise, if a standard key was pressed, KBD would be used as 
an index into the keyboard layout look-up table (page $17). KBDFLG 
and the modified value of KBD are then stored in the typeahead bufiBf 
The console driver will retrieve them when it feels so inclined. 

Before exiting, the keyboard interrupt handler also checks to see if 
the "any-key" event is armed or if this is the "attention" event character. 
If so, the handler queues up the appropriate "event" Later, before re- 
turning to the user program, SOS checks the event queue and transfers 
control to the event handler as a subroutine. 

SOS Data and Jump Tables: $1900..19FF. The first few bytes on 
page $19 contain important status information (table 4). During ordi- 
nary business, some (or all) of these bytes control the video generator 
and/or similar accessory apparatus. But when the monitor is running, 
they have no perceptible effect. So there must be more than one way to 
control the video generator. 

' _____ __ 

1900: 10 ?? 

1901: 06 Highest user memory bank. 

1902: 00 Console control #7 and #9. Setting bit 7 suspends screen 

output; bit 6 will "flush" screen output. Low nibble: ?? 
1903: 00 High bit set indicates NMI pending. 
1904: 8F ?? 
1905: 19 7? 

1906: 82 Console control #5. Clearing bit 7 turns off video. Bit 6 may . 
be involved in graphics. Low nibble contains text mode 

[0-2]. 

1907: 00 Number of pages allocated for graphics. 
Table 4. SOS status info. Some bytes control video generator. 

Page $19 also contains a jump table beginning at $1910. The jumps 
take the form "1913: 4C CA E2 JMP E2CA". The table provides fixed 
entry addresses for certain subroutines that apparently will be supported 
in future versions of SOS. The list is in table 5. Those marked with an as- 
terisk are documented by Apple and are legal to use. The others . . . well, 
they do appear in the jump table. 



Access 


SOS address 


* = Legal to use 


1910 


198F 


Probably debug. 


1913 


E2CA 


* AllocS I R: Allocate internal resource. 


1916 


E352 


* DealcSIR: Deallocate internal resource. 


1919 


E3C2 


Disable reset key (unless NMI pending). 


191C 


E3F3 


Enable reset key (just sets FFDF bit 4). 


191F 


E41D 


* Queevent Queue an event. 


1922 


E3A9 


* SelC800: Grab $C800 expansion space. 


1925 


EE2A 


Writes "system failure." the value of A, and 






hangs. *u 


1928 


EE17 


* SysErr: reports errors from drivers to caller 


192B 


F5C5 


? error number look-up for internal buffer 






allocation. 


192E 


F68ff 


? error number look-up for internal buffer 






allocation. 


1931 


F710 


? error number look-up for internal buffer 






allocation. 


1934 


19D3 


Probably debug (AND #20, STA 19D2, RTS). 


1985 


1910 


Probably debug. 



Table 5. Supported SOS subroutines. 



Page $19 also contains a copyright notice at $1990, a few other data 
bytes of mysterious function, and a lot of zeros. The subroutine SysErr 
stores the error number at $1980 and the return address at $19FD and 
$19FE. The "system-failure" routine uses the end of this page to store the 



l Source: David T. Craig 



"_59.PICT" 1 298 KB 2001 -08-22 dpi: 600h x 600v pix: 4675h x 6368v 

j Page 0005 of 000~ 



Apple III Computer Information • Doc #01 3 • Jeppson: Guided Tour of Highway /// 



106 



FTA LK 



MAY 1983 



program counter and all register values for use in debugging. Other SOS 
routines store various temporaries on this page. 

The copyright notice at $1990 is a good spot if you want to store 
things that can be found from the Monitor. If you want to store a lot of 
stuff you can also use the character set area. 

Those Registers: the Onboard 6522 VIAs. The two VIAs are re- 
ferred to as D-VIA (5FFD0..FFDF) and E-VIA (5FFE0..FFEF) re- 
spectively. They are fully occupied with Apple III hardware manipula- 
tions. You cannot, for example, use the VIA timers for your own pur- 
poses. The VIAs manage bank-switching, zero-page selection, and much 
of the other machinery that permits Apple III to accommodate the 64K 
address space of the 6502 cpu chip. 

$FFEF: Bank register (E-VIA IORA). The low nibble selects the cur- 
rently switched-in bank. The high nibble is generally $F. Attempts to 
change the high nibble have no effect. Those four bits are flags for inter- 
rupt requests from the slots. 

$FFDF: Environment register (D-VIA IORA). Table 6 lists the sig- 
nificance of its bits. Apple would be happier if you confined your atten- 
tion to bit 7 and didn't mess with the others. Table 7 contains a variety of 
information about the various standard environments. 

SFFDO: Zero-page register. Selects the current zero page, which can 
be assigned to any page in memory. If alternate stack is enabled (bit 2 of 



Value Bit 


Function 


Bit-0 


Bit - 1 


01 


F000..FFFF 


RAM 


ROM 


02 1 


ROM# 


ROM#2 


ROM#1 


04 2 


stack 


alternate 


normal (true 0100) 


08 3 


C000..FFFF 


read/ write 


read only 


10 4 


reset key 


disabled 


enabled 


20 5 


video 


disabled 


enabled 


40 6 


C000..CFFF 


RAM 


I/O 


80 7 


clock speed 


2MHz 


1 MHz 


Note: ROM#2 doesn't exist. 








Table 6. Environment register ($FFDF). 



(Data mostly from unpublished SOS Reference Manual) 



Environment register 

Clock speed 

I/O space 

Screen 

Reset key 

Write protect 

Stack 

ROM 
Zero page 
Xbytepage 
Bank register 
6502 interrupts 
Functions allowed: 

Issue SOS call 

Be interrupted 

Handle interrupt 

Queue event 

Handle event 

Allocate SIR 

Call SelC800 

Call SysErr 



User 

$38 
2 MHz 
disabled 
on 

unlocked 

read only 

alternate 

disabled 

$1A 

$16 



Kernel 

$34 

2 MHz 

disabled 

unchanged 

unchanged 

r/w 

normal 
disabled 
$18 
$14 



unchanged unchanged 
enabled enabled 



yes no 
yes yes 
no no 
yes no 
yes no 
yes yes 
see text yes 

— no yes 

Note: Upon entry to an interrupt handler X 
scratchpad area on zero page. These bytes 
$00,X and so on. If the interrupt source is the 
contains the ACIA status register. 

Table 7. The standard environments 



Driver 


IRQ 


Monitor 


$74 


$74 


$77 


2 MHz 


2 MHz 


2 MHz 


enabled 


enabled 


enabled 


unchanged 


unchanged 


on 


unchanged 


unchanged 


unlocked 


r/w 


r/w 


r/w 


normal 


normal 


normal 


disabled 


disabled 


enabled 


$18 


$00 


$03 


$14 


none 


none 


unchanged 


handler's 


$F0 


enabled 


disabled 


?? 


no 


no 


no 


with care 


with care 


n/a 


no 


yes 


n/a 


yes 


yes 


n/a 


no 


no 


n/a 


yes 


yes 


?? 


yes 


yes 


n/a 


yes 


no 


n/a 



points to a $20 byte 
should be addressed 
onboard ACIA then Y 



SFFDF is clear) then all stack-using opcodes use the current zero page 
XOR $01. Extended addressing, on the other hand, functions only for 
zero pages in the range $18.. IF. The user zero page is $1A. That's you 
and/or the interpreter. Drivers and SOS.Kernel use $18. Interrupt han- 
dlers use $00. SOS is supposed to decide these things; you are not. The 
SOS call handling routine even checks to see if the caller's zero page is 
$1A. If not, it crashes the system. Somewhere in darkest Cupertino, Ap- 
ple maintains a coven of witch doctors who will cheerfully do unspeak- 
able things to your image, should you violate this trust. 

SFFDD: "Any-slot" interrupt flag. When a peripheral card in one of 
the slots pulls down the interrupt line, the interrupt handler is entered 



with 6502 interrupts disabled. The interrupt handler is, of course, re- 
sponsible for clearing the interrupt condition on the card. If the inter- 
rupt handler wishes to enable 6502 interrupts (as it should if it will run 
longer than 500 microseconds) then it must also clear the "any-slot" in- 
terrupt flag by storing $02 in $FFDD. Otherwise the interrupt manager 
will do it for you when the handler exits. 

I/O Space: $C000..CFFF. I/O space is on-line when bit 6 of the en- 
vironment register ($FFDF) is set. It is actually $C000..C4FF and 
$C800..CFFF. The intervening bytes $C500..C7FF are always RAM. 
Table 8 lists those registers of which we have some clue. There are many 
mysterious others. When in doubt, there is a good chance that a regis- 
ter's function is similar or identical to its role in Apple II. 



C000 
C008 
C0 10: 
C020 
C030: 
C040: 



KBD. ASCII value of the most recent keypress. 
KBDFLG. Bits are flags for modifier keys. 
Clear keyboard strobe. 

Deselect all peripheral slots (CFFF more commonly used). 
Clicks speaker (Apple II type). 
Beeps speaker (Apple III type). 



Soft switches 

C050: Black and white on. 

C051: Color on. 

C052: Forty-column mode, low-res mode. 

C053: Eighty-column mode, hi-res mode. 

C054: Display buffer 1. 

C055: Display buffer 2. 

C056: Text on. 

C057: Graphics on. 

Peripheral card I/O (each slot has $10 bytes) 
C090: Slot 1 . 

C0A0: Slot 2. Normally addressed as C080.X 

C0B0: Slot 3. where X = sO (slot number in high nibble). 

COCO: Slot 4. Note: there is no slot 0. 

Onboard 6551 ACIA 



C0F0 
C0F1 
C0F2 
C0F3 



ACIADR Data register. 

ACIASR Status register. 

ACIAMR Command mode register. 

ACIACR Control register. 



Peripheral card PROM space (one page for each slot) 



C100 
C200; 
C300 
C400: 



Slot 1 . 
Slot 2. 
Slot 3. 
Slot 4. 



Table 8. I/O space: $C000..CFFF. 



Notice that the $10 bytes beginning $C080, $C0D0, $C0E0, and 
$C0F0 are not used for slots in the III. In Apple II they would be slots 0, 
5, 6, and 7 respectively. There may or may not be a clue to their function 
in the assignment of various connecting plugs to imaginary slots in emu- 
lation mode. For example, $C0F0+ is the ACIA (asynchronous com- 
munication interface adapter), as indicated in table 9. The ACIA runs the 
serial port, which in emulation mode is assigned to an ethereal slot 7. 
Similarly, emulation mode assigns the floppies to slot 6, and the floppy 
drivers (buried in SOS.Kernel at $E899) probably access bytes in 
$C0E0..C0EF, and in $C0D0..C0DF as well. But this may only be spec- 
ulation. 

Entry: A = slot number ($00 deselects all slots) 









Entry point: 


(via J MP table) at $1922 


E3A9: 


C9 


05 




CMP 


#05 


; range check 


E3AB: 


B0 


14 




BCS 


->E3C1 


; error returns carry set 


E3AD: 


08 






PHP 






E3AE: 


78 






SEI 




; disable 6502 interrupts 


E3AF: 


8D 


CO 


DF * 


STA 


DFC0 


; save slot number 


E3B2: 


09 


CO 




ORA 


#C0 




E3B4: 


8D 


BF 


E3 • 


STA 


E3BF 


; build instruction at E3BD 


E3B7: 


2C 


20 


CO * 


BIT 


C020 


; deselect strobe 


E3BA: 


2C 


FF 


CF * 


BIT 


CFFF 


; same 


E3BD: 


2C 


FF 


CO * 


BIT 


C0FF < — 


; becomes CsFF 


E3C0: 


28 






PLP 




; restore 6502 interrupts 


E3C1: 


60 




* 


RTS 







Table 9. SelCSOO disassembler listing. 
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SC800 CFFF is a 2K pcnphcral card expansion space used "in com- 
mon by all the slots As in Apple II it can be selected by referencing one 
oi trie peripheral card I/O locations assigned to that slot. SCFFF does 

nr^^l S ^ tS \n t , $C ? 20 (f0rmCr,y thC 0Ut P Ut t0ggIc > » the 

preferred Apple III deselection strobe. 

There are some new rules for using 5C800 space that are intended to 

mesh with Apple Ill's interrupt-driven operating system. You are sup- 

%E£ZS?T thC ? aCC Pri ° r 10 USC by ca,,in « thc SOS subrouunc 
SeOOO. The slot number is passed in the [AJ register on a JSR to the en- 
try point at $1922. (See the subroutine listing in table 9.) A value of $00 
deselects all slots. Note that SeOOO saves the slot number in $DFC0- 
this allows the interrupt manager to restore the proper card allocation 
should an interrupt occur. The interrupt manager routinely deselects all 
slots on entry and reselects the proper slot on the way out 

The documentation states that SelC800 may be called from any en- 
vironment including interpreters (except an NMI handler). This turns 
out not to be entirely true. The subroutine builds an instruction on-the- 

w. ^n^u hC u S,0t nUmbcr ° RA I™ 35 high ^ of oi*™d in 
bit 5C0FF. The bit instruction then physically enables $C800 space for 
that slot. But this area of SOS is write-protected while running in thc user 
eny,ronment, so the STA instruction doesn't work and the subroutine 
tails without notifying you. If you want to call SeOOO from the user en- 
vironment you must enable write by clearing bit 3 of the environment 
register ($FFDF). 

There must be another soft switch somewhere. When you enter the 
Monitor (with control-open-apple-reset), it comes up in forty-column 
mode. You can change to eighty-column mode with escape-8, and back 
again with escaped. From eighty-column mode you might suppose you 
could also change back to forty columns by fiddling with the soft 
switches, perhaps by reading $C052 and maybe $C054. Things change 
and you can tell it's really trying hard. But no combination quite makes' 
it. We don't know why. 

System Internal Resources: SIRs. When an interrupt occurs the in- 
terrupt manager must know which interrupt handler goes with which in- 



terrupung device and where the handler address is located in memory. 
The SIR allocation scheme provides a look-up table. It also establishes 
ownership" of a resource in order to prevent squabbles. Resources 
should therefore be allocated whether there will be interrupts or not 
Somewhere in your code, place thc following data table: 
SIRADDR .equ SIRTABLE 



SIRTABLE 



byte 
byte 
.word 



00 
00 

handler 



byte bank 



; SIR# 

; ID code (will be assigned by SOS) 
; interrupt handler address (or 
$0000) , 
; interrupt handler bank 



J 18 P crforracd b y J SR AllocSIR ($1913) and dealloca- 

c?o A b ^l R ^ Ca,cSIR ($,916) - 6502 rc » stcrs must contain: X - 
c £r\£ R; Y * SIRADDR+1; A - total number of bytes* 
SIRTABLE. This will be $05, or some multiple of $05 in thc event that 
several resources are allocated at the same time. AllocSIR returns with 
carry clear if the resource is successfully allocated. 

Table 10 lists thc numbers assigned to various resources. Examina- 
tion of AllocSIR suggests that the range is $00.. 17. There are a lot of 
question marks. One wonders about the digital/analog audio converter 
the paddle ports and other mysteries, such as whether the interrupt line 
of the MM58I67A clock chip is wired up 



Ink Well version 2.2 

Word Processing for the Apple /// ™ 

One Big Advantage 

(and lots of little ones) 

The Big Advantage . . . Ink Well displays your 
document on the screen just as it will he 
printed. You can format your documents 
on the screen, and know exactly how 
they will look on paper. Ink Well even 
shows you where the page breaks will 
fall. 

The Little Advantages . . . Typewriter Mode, 
Merge Print, underlining, double strike, 
over print, headers, footers, page 
numbering, inbedded control charac- 
ters, word wrap, right justification, 
centering, adjustable margins and tabs, 
find and replace, block movement, and 
price . . . only H85. 

Foxware Products - (801) 364-0394 
165 West Mead Ave., Salt I^ike City, lit. 84101 

Apple is a registered trademark of Apple Computer, Inc. 



SIR# 

00 
01 
02 
03 
04 
05 
06 

07 OF 

10 

11 

12 

13 

14 

15 17 



Resource 

(?) 

ACIA 

keyboard 

(?) clock chip *» 
(?) 

used by console screen code 22. "SYNC" 

character set downloader interrupts 

(?) 

(?) character set downloader 
slot 1 
slot 2 
slot 3 
slot 4 

(?) pseudo slots 5-7 



Table 10. Internal system resource numbers (SIRs). 

Boot Sequence: On power-up, or after control-reset, the boot oroc- 
ess begins in ROM#I (ROM#2 doesn't yet exist). Low-level diagnostics 
are performed. Then block is read from the disk in the built-in drive 
This is the SOS boot code and is present or/every disk that has been for- 
matted by the System Utilities program. It must be present for a success- 
ful boot. It consists of one block of "absolute" code and is loaded into 
the computer at SA000, where it begins to run. 
r JI^u °° de bCginS by bcating and swit cnmg in the highest bank 

?L t , I " 11 gOCS back t0 thc disk and ,oads in fiv * more blocks 
(blocks 1.. 5). These are placed in 5A200..ABFF. Block 1 currently con- 
tains all zeros; blocks 2..5 are the disk directory. The boot code then 

TcfJ™ d ^° ry and l0CatCS SOS Kernc »> *hich it loads into memory 
at $lE00..73rF. 

c™ h ^° SKern L d beginS running ' k P ro mptiy relocates bytes 
S2?L f £ t0 > ^ 3rea $BC00 " FFFF - This is the functional 
bUJ>.Kernel. The loader portion is eventually overwritten and discarded 
First however, it locates and loads SOS.Interp and loads the drivers 
from SOS.Driver. It then initializes SOS.Kernel and each of the drivers • 
Finally, control is transferred to the first instruction in the interpreter and 
you are in business. 

Data Disks: Your Own Boot Code. If you want to end up in Apple 
III native mode, the boot process had better find the SOS boot code in 
block on the disk in the built-in drive. Any disks you ever expect to use 
as SOS boot disks must have that code. On the other hand, you may 
wish to create data disks that have the SOS directory structure but can- 
not be booted. Or you may want thc disk to boot, but to end up with 
some entirely different operating system in the machine, such as an emu- 
lator, for example. For either of these alternatives you will want to put 
your own code in block on your disk. 

You start with a single block: the 512 bytes contained in block It 
will be loaded and begin to run at $A000. You may then use the ROM 
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subroutines to load in more blocks, so you can actually requisition as 
<ch space as you require. At the time your code begins to run, you will 

n the Monitor or something very similar. The environment register 
reads $77, zero page is $03, and bank is switched in. You have avail- 
able all the hardware, including the VIA registers, extended addressing 
iwith proper zero page), and all the internal resources. You do not, of 
ourse, have any of the SOS subroutines and facilities. 

Your code should be assembled as 4, absolute ,, code by the Pascal 
■ 502 assembler and should be ".org'd 1 ' on $A0O0. For data disks it 
should end in an infinite loop. Word Juggler, for example, creates data 
disks that, when you try to boot them, print "Can't boot Word Juggler 
data disk" in the middle of the screen and politely hang the computer. 

Formatting Data Disks. After you've assembled your own boot 
^de, it is a relatively simple matter to format data disks from applica- 
tion programs. It can be done entirely from Pascal and almost entirely 
from Basic. From Basic you will also need an invokable module that will 
write to a floppy disk by block number, just as Unitwrite will do in Pas- 
jal. The assembly source text for such a module is appended at the end of 
ihis article. 

The floppy format driver (FMTDX) is activated by issuing a DCon- 
trol call, code number 254 ($FE), to the appropriate driver (.FMTD1 for 
the built-in drive). In Pascal this is done with Unitstatus procedure. In Ba- 
sic you use the Request.Inv invokable module that comes on the Apple 
III Basic boot disk. If you're working in assembly you just issue SOS call 
$83. When the DControl call is issuedrthe format process begins imme- 
diately. All error checking and confirmation requests must be done by 
your program before you issue the call. 

The DControl call must specify a control list buffer. FMTDX.Driver 
expects a one-page (256-byte) buffer that will be reproduced on each page 
of the new disk. Normally this buffer should contain all zeros. The for- 
matter places address code on each track and sector and fills the data 
;lds with zeros, or whatever you put in your buffer. Then it quits. 

You now have a formatted disk. It is not yet a SOS disk. It contains 
neither a directory nor the block boot code. You must store those your- 



self from program buffers using Unitwrite (if you arc working in Pas- 
cal). If you ever want to use the disk as a SOS boot disk, just copy block 
from some other boot disk. Otherwise transfer your own code. Re- 
member to chop off the header block, which the assembler will have 
placed in front of your code. Start the transfer at block 1 of the oodefile. 

Next you must install a directory. The minimum requirements for a 
usable SOS directory are listed in table 11. You must store the indicated 
byte values on the disk. Just put them in the proper place in the 51 2-byte 
buffer and write the whole block onto the disk. 

The boot code— blocks 0..1 (bytes 0000.. 03FF on the disk) 
Your code, or the SOS code from another boot disk 

The directory— blocks 2.. 5 (bytes 0400. .0BFF) 
0400: 00 00 03 00 

0404: Fx— where x is the length o< the desired volume name in the 
low nibble. The high nibble should contain F, for root directory 
0405: The volume name in ASCII capitals (do not prefix with "/") 
0414: 75 

0422: C3 27 0C 00 00 06 00 18 01 

(These last two words are 0600 = the block number of 

the bit map 
01 18 = 280 dec. - blocks 
on volume ) 

0600: 02 00 04 00 
0800: 03 00 05 00 
0A00: 04 00 00 00 

The bit map— block 6 (bytes 0C00..0CFF) 
0C00: 01 FF FF FF FF.. .through byte 0C22 

Table 11. Minimum requirements for a SOS disk. 

Word Juggler manages to write all this information onto the disk by 
a short segment of elegant and compact code. The utilities program uses 
the brute-force approach. It simply includes fourteen pages of a stan- 
dard SOS structure (mostly zeros) and transfers the whole thing to disk 
in one piece. No wonder the utilities program is 123 blocks long. 

Unitrcad and Unitwrite for Basic: an Invokable Module. Th< 



PROTECT AND ORGANIZE 

Your Apple ll-lle System 



COOL STACK — SENTRY II 



IT LOCKS — Locks the Apple II computer and disk drives to 
base plate and separate adhesion plate secured 
to table top. 

IT COOLS — Extends the life and reliability of the computer 

and peripheral plug-in boards. 
IT STORES — Provides neat and efficient organization of the 

entire computer station including manuals and 

disks. 

IT TILTS — Allows fast easy access to inside the computer. 
Precision all steel construction provides optimum strength and durability color 
matched to the Apple II computer. 

PRINTER PAL - Provides paper storage beneath printer. Paper guides included. 
Models available for most printers. 

'APPLE is a trademark of Apple Computer, Inc. 
CdOL STACK and PRINTER PAL are trademarks of FMJ, Inc. 





COOL STACK-STANDARD 

For those who do not need 
the extra security and fre- 
quent easy access to inside 
the computer. Includes fan 
and library rack. Holes pre- 
punched to lock in disk 
drives and optional Power 
Sentry. 



POWER SENTRY 

4 A.C. outlets with transient suppression controlled by a keylock switch. 
Separate rocker switch to "RE-BOOT" the Apple. Includes security bracket 
to prevent removal of plugs deterring theft of monitor and printer. 

DISKLOK 

The DISKLOK prevents unauthorized access or tampering with the Apple Disk 
II drive. DISKLOK can be used on the disk drive alone or with the Cool Stack. 
Easily installed utilizing existing holes in disk case. 

FOR MORE INFORMATION ON THESE AND OTHER PRODUCTS CONTACT YOUR 
DEALER OR: FM), Inc., P.O. Box 5281. Torrance, C A 90510 (213) 325-1900 
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Devioe.IO.Inv invokablc module contains two procedures. In Basic they 
are external procedures and require the perform statement (see page 162, 
Apple Business Basic Manual). 
The procedures are 

unitread (% devnum%, @ buf% (0), % length%, % block /© ) 
unitwrite (% devnum%, @ buf% (0), % length%, % block% ) 
These procedures read from or write to a specified block number 
(block%) on the disk in a specified device number (devnum%). They 
transfer 0«gth%) bytes to or from the buffer in memory. The buffer 
must contain enough bytes or Unitread will spill data over onto sur- 
rounding memory with disastrous results. Normally the buffer should be 
dimensioned as an integer array; for example, DIM buf%(512). This 
buffer will contain more than enough room for two blocks (1 ,024 bytes). 

Unitwrite is a dangerous procedure. There is absolutely no protec- 
tion from errors. It is easy to write all over a disk directory, destroying it 
and rendering the entire disk unusable. 

The device numbers of the floppy disks are .Dl - 1, .D2 - 2, and 
so on. 

After typing in the text, save it to any pathname, perhaps Devio.Text. 
Then assemble it to the corresponding codefile, Devio.Code. Finally, 
change the name to Device.IO.Inv. If the assembler is not allowed to ap- 
pend the suffix .code, the file-type designation will get all screwed up and 
it won't invoke. 

pop 



.macro 
pla 
sta 
pla 
sta 

.endm 

.macro 

Ida 

pha 

Ida 

pha 

.endm 



%1 



push 
%1 + 1 

%1 



Z-80 PLUS! 




• Totally compatible with all CP/M software. 

• Executes the full Z-80, 8080 and 8085 instruction set. 

• Fully compatible with Microsoft disks (no pre-boot 
required). 

• Does everything the other Z-80 cards do plus supports 
Z-80 interrupts. 

• An on-card ROM eliminates many I.C.'s for a cooler, 
less power consuming board. 

• Runs on any Apple II, 11+ or Me with at least 48K 
memory (80 column card is not required). 

• The Z-80 Plus runs: dBase II, WordStar, Spell Star, 
Cobol-80, Fortran-80, Peachtree and .aj/ other CP/M 
based software. 

• Complete documentation included (user must furnish 
software) . 

• High quality P.C. board, gold plated connector, all 
I.C.'s in high quality sockets, with mil. spec, 
components used throughout. 

• Two year warranty. Pr|ce $1 39 00 

Add $10.00 If Outside U.SA 



Send Check or Money Order to: 
APPLIED ENGINEERING 
P.O. Box 470301, Dallas, TX 75247 
All Orders Shipped Same Day 



To Order By Phone Call (214) 492-2027 
7am to 11pm 7 days a week 
MasterCard & Visa Welcome 
Texas Residents Add 5% Sales Tax 



DRead 
DWrite 



buffer 



return 
devnum 

paramO 

paraml 

param2 

length 

block 



start 



.macro 

brk 

.byte 

.if 

word 

.else 

word 

endc 

.endm 

.equ 
.equ 

.equ 



jmp 

.word 
.word 

.byte 
.byte 
.word 
.word 
.word 



.equ 
pop 
pop 
pop 
pop 

P£ p 

sta 

Ida 

sta 

SOS 

push 

rts 

.proc 

.ret 

.ret 

pop 
pop 
pop 
pop 
pop 
Ida 



Ida 

sta 

SOS 

push 

rts 

.end 



SOS 

%1 

.. %2 "<>"" 
%2 

pa ram 



0E8 



.proc unitread,4 

.def return,devnum,param0,param1 
.def param2,length,block 



start 

0000 
0000 

00 
00 

buffer 
0000 
0000 



param8 .word 0000 



return 

block 

length 

buffer 

oevnum 

#05 

paramO 

devnum 

paraml 

DRead 

return 



; number of parameters 
; device number 
; pointer to buffer 
; bytes to read/write 
; block number to begin 
read/write 

; bytes read - result 



-* ; pop procedure parameters 

; number of parameters for 
DRead 

; transfer one byte 

; issue DRead SOS call 



unitwrite, 4 

return, devnum, paramO.param 1 
param2,length,block 



return 

block 

length 

buffer 

devnum 

#04 

paramO 

devnum 

paraml 

DWrite 

return 



pop procedure parameters 



number of parameters for 
DWrite 



transfer one byte 
issue DWrite SOS call 



XFR. Block is a short Basic program intended to illustrate use of 
these procedures. It transfers whole blocks (512 bytes each) between 
specified block numbers on (separate) floppy disk drives. 

10 INVOKE "device. io.inv" 
20 DIM buf% (512) 

30 HOME: PRINT "Transfer disk blocks utility" 
40 PRINT 

50 INPUT "Source device number: "; source% 
60 INPUT "Destination device number: "; dest% 
70 INPUT "Number of blocks to transfer (0..2): "; blks 
80 length% = CONV% (blks * 512) 
90 INPUT "Block number to begin reading: "; readblk /© 
100 INPUT "Block number to begin writing: "; writeblk% 
110 PRINT: PRINT "Press any key to begin transfer": GET g$ 
120 PERFORM unitread (% source%, @ buf% (0), % length%, 
% readblk%) 

130 PERFORM unitwrite (% dest%, @ buf% (0), % length%, 
% writeblk% ) 

140 PRINT: PRINT "DONE" 1 



l Source: David T. Craig 
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